COMMENT ⊗   VALID 00011 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002		    Using REVED		26 June 1977
C00004 00003			Unit reverberators
C00008 00004			Complex reverberators
C00012 00005			The pointer
C00015 00006			Impulse responses
C00017 00007			Files
C00020 00008			State information
C00022 00009			Error handling
C00025 00010			Further information
C00026 00011			Example
C00038 ENDMK
C⊗;
	    Using REVED		26 June 1977
	Please don't worry too much if this overview seems terse and
sketchy; it is purposely abbreviated because the program itself is
highly interactive and largely self-explanatory.  The effects of most
commands will be obvious, and a brief explanation of any command is
always available on request.  The feeling is that it is easier to try
out things and see what they do than to decipher a long-winded
explanation which still leaves questions.
	Most interactions with REVED will center around two major
structures.  These are discussed below, along with a few other
necessary or useful capabilities of REVED.  No attempt is made,
however, to give a complete tutorial on reverberator design; only the
rudiments of using this particular design program are laid out.
	End products of REVED are complex reverberator designs which
are intended to simulate the overall acoustics of a room.  Input to
the complete reverberator is monophonic, and output is any number of
channels (although the music compiler handles a maximum of four).
Complex reverberators are built up by connecting simple unit
reverberators together.  Therefore, the first conceptual structure
that must be understood is the unit reverberator.
		Unit reverberators
	Currently, REVED supports only one kind of unit reverberator,
the first-order all-pass.  Several different interdependent parameters
are useful in describing and understanding these units.  By giving
appropriate commands it is possible to change any of the parameters
displayed for a special "scratch" unit.  Typically, this scratch unit
would be altered until it was satisfactory, and then a copy of it
would be linked into the complete reverberator where desired.  All
commands altering unit parameters apply to this special scratch unit,
never to units already linked in.  In the event that a unit previously
linked in needs to be altered, it may be copied into the scratch unit,
changed, and replaced.  To change the value of a parameter, simply type
the name of the parameter (first letters are sufficient) followed by
the new value.
	Because the parameters are interdependent, a change in one
of them will affect others.  Sometimes it may be desirable to specify
that a certain parameter will be held fixed when another is changed.
One of three parameters may be so specified by giving its name (again,
first letters suffice) after the new value in a parameter changing command.  
In general, allowable choices are GAIN, DELAY, and TIME; but specific
commands may not permit all of these as possiblilites (because of the
interdependencies).
	An additional feature is that the current GAIN or DELAY may be
changed by multiplying or dividing it by some factor, rather than by
stating the new value explicitly.  To do this, type "*" (or "/")
followed immediately by the factor instead of typing the new value in
these commands.  If the factor itself is omitted, the last factor typed
for that command will be used.  A slight variation of this format
applies to the #Samples command: substituting "+" (or "-") followed by
an integer in place of the new value causes the resulting value to be
that many prime numbers greater (or less) than the current value.  Here,
too, the last increment typed is used as the default if the integer is
omitted.  By popular demand, the initial defaults for GAIN and DELAY
may be restored by attempting to explicitly set their values to zero.
Similarly, their default factors may be restored by making them explicitly
zero -- which will also restore the associated value default.  These
features are intended to facilitate the construction of complex
reverberators, discussed below.
		Complex reverberators
	As was mentioned before, complex reverberators are made by
connecting many unit reverberators together.  Only a restricted form
of connection is allowed in REVED, namely, a unit can get its input
from only one source -- either the input signal, or the output of
an intervening unit.  Units are permitted to give their outputs to
any number of succeeding units.  When this multiplicity of outputs
occurs, it will be referred to as branching (since a diagram of the
connections bears some resemblance to a tree with its root at the
input signal).  The "leaves" of this tree will be the outputs  of
the whole reverberator, and a typical finished tree will exhibit a
pleasing symmetry in its branching.  Unfortunately, limitations in
display capabilities make it impractical to actually draw such a
tree on the display screen.  Instead, a familiar indentation notation
-- like that used for outlines in books and papers -- is used to
indicate the connections among the units.  One slight refinement is
added for convenience, though: so long as there is no branching in
the units listed so far, the list of units will not be indented.
A simple example should serve to illustrate the relationship between
the tree structure and the indented listing.
	Consider:

[Input Signal]
[Unit 1]
[Unit 2]
   [Unit 3]
      [Unit 4]
      [Unit 5]
   [Unit 6]
      [Unit 7]
      [Unit 8]

In the actual display, of course, the units will be described by a
few parameters, not by name, but here the names are helpful.  In this
case, Unit 1 gets input from the Input Signal, and gives its output to
Unit 2, which (as required) gets input from no other source.  Next,
Unit 2 gives its output to both Unit 3 and Unit 6.  Continuing in like
manner, Unit 3 gives its output to Unit 4 and Unit 5, both of which
are "leaves" of the tree, and so give their output to appropriate output
channels for the whole reverberator.  Similarly, Unit 6 gives its output
to Unit 7 and Unit 8, which are also connected to output channels.
		The pointer
	For purposes of editing the tree, the screen display will
include one other item, a pointer into the tree.  Any commands
involving the tree (except when treated as a whole) will depend on
the location of this pointer.  Three commands are provided for moving
around in the tree; all of them are single character commands and
do not require a carriage return after them (unless some other command
was typed first and then backspaced over). A left-pointing arrow
moves the pointer to the input source for the current unit; since
there can be only one, this is simple.  To move to the output of the
current unit is less defined in the presence of branching.  The
convention used is that a right-pointing arrow moves the pointer to
the first output listed (if any), and a double arrow moves from that
output down to subsequently listed parallel outputs.  Consequently,
left- and right-pointing arrows are not exact inverses, nor is there
an inverse for the double arrow command.  In practice, this should
prove no problem.  On a standard Stanford keyboard these characters
are all grouped together under the right hand, permitting quick,
convenient pointer moving.
	All of the parameters of the unit that is currently being
pointed at (the current unit) will be displayed with the previously
mentioned scratch unit using the same format.  This makes comparison
easy (a frequent desire).  Commands exist to copy either one into the
other; to delete the current unit; and to insert a copy of the
scratch unit into the tree, linking it either before, after, or in
parallel with the current unit.  In addition, when an impulse
response is requested, it is computed along the path from the input
signal up thru the current unit.
		Impulse responses
	Impulse responses are valuable tools for building good
reverberators.  They provide a picture of how the reverberator
will respond when the input signal is a single sample of unit
amplitude -- and thus how it will respond to any signal.  If
a reverberator performs poorly, examining impulse responses at
various points along a path thru the reverberator will usually
indicate where things went wrong.  High quality reverberators
exhibit a smooth, dense, exponential decay.  Since these qualities
are normally discernable after a relatively small number of
samples have been computed, and since the computation itself is
moderately expensive, a time or factor of the default time may be
specified in the impulse command.  As before, the factor will be
remembered.  (It, too, can be reset to its initial default value
by setting it to zero.)  Also, the display may be remembered in a
file by naming a file in the command.
		Files
	Finally, the tree structure may be written into a file
in a form suitable for execution by the music compiler, or the
whole state of the editor may be saved as a list of commands
which may be read in on some later occasion if further editing
is desired.  In fact, any list of commands at all is acceptable
for file input, with one exception: file input may not be requested
within a file.  Furthermore, if REVED is started in RPG mode (if
you don't know, it's ok), the first thing it will do is try to
read in a file of commands.  The file read from is the same one used
as the default for saving and restoring the state by interactive
command.  Using this capability, clever programs can start REVED
in whatever state they wish.
	Whenever a file name is permissable, any fields of the
name -- including DEVICE,FILE,EXTENSION,PROJECT, or PROGRAMMER
in the usual syntax DEVICE:FILE.EXTENSION[PROJECT,PROGRAMMER] --
may be omitted, in which case the default for that field will be
filled in.  A simple way to get the entire default name is to
use ":", which gets the defaults filled in everywhere.  There is
a subtle difference in interpretation between "[PROJECT," and
"[PROJECT" (i.e., without the comma), in that the former uses
your logged in PROGRAMMER name, while the latter uses your ALIAS.
		State information
	Consonant with the "what you see is what you get" approach to
user interfaces, REVED has no hidden state information.  Any internal
variables that affect the interpretation of a command are both visible
and settable (with the uninteresting exception of default file names).
Aside from the larger structures that have been discussed, there are
the saved defaults for multipliers.  These are displayed beside the
label for the corresponding parameter; the multiplier for impulse
responses is beside the Time label. (It is displayed as [I*.xxx] to
avoid confusion with the other kinds of multipliers.)  Lastly, there
are two items displayed next to the #Samples label: the primes offset
(displayed as (+x) ), and the value of the Nearest_primes switch (Y for
use nearest primes, N for don't use them).  The default file name
assumed for any command may be found by asking for a description of that
command.
		Error handling
	In the unlikely event that REVED finds a command unsatisfactory,
it will print a message to that effect.  Error messages will typically
give the name of the internal procedure that was unhappy, followed by
the allowable range of the argument that made it unhappy.  Since the
message is stated in terms of entities known internal to the program,
the messages will not always make literal sense if interpreted for
external meaning.  For example, when changing the scratch unit the
internal names for the FIX parameter are different from the names
typed by the user.  In particular, the name "decay" is used internally,
while the name "time" is used externally (to make the name unique when
only a single character is typed).  Despite this awkwardness the error
reports should be fairly easy to decipher -- most of them having
obvious causes.  One additional class of errors should be mentioned,
though hopefully one of these will never occur.  It is possible that
the SAIL runtime routines will complain about something.  The most
likely thing is numerical errors, such as overflow or underflow, from
the LOG or EXP routines.  These numerical errors are not fatal, and
may be handled by typing [RETURN] to the "↑" prompt SAIL will give.
No matter what the error, SAIL will type a list of options in response
to a [SPACE].  (The bracketed names above mean type the single
character with that name.)  If neither REVED nor SAIL catches a bad
error, it is theoretically possible to get an error message from the
monitor.  This has never happened -- yet.
		Further information
	Information about specific commands will be provided by REVED
upon request.  More detailed information about any aspect of REVED may
be obtained from either the source code or the author -- whichever you
can get your hands on.  An overview of the implementation and guide to
the various files involved may be found in REVED.DOC, wherever the
source files for REVED are kept.
		Example
... The following text is an annotated example of using REVED.  Naturally
... it will suffer somewhat from not being able to show the changes in the
... display.  To remedy that, try typing in commands one at a time, observing
... their effect.  If all goes well, the effect should be the same as using
... this page (minus title) as a command file.  The reverberator constructed
... here is not a particularly good one, and is intended only as an example
... of how to use the program.

... The first thing to do is type "R REVED" to the monitor to call up the program.
... You should now see a display of various kinds of things, with a list of
... commands at the top of the screen, and command echoing at the bottom.

Clock_rate 128
... Most music is done at 12800 until perfected.  This command assures that the
... reverberator designed here is compatible with that.

Time_to_decay 3.0 gain
... Starting with the overall decay time and working down to shorter delays is
... a popular way to proceed.  Here we assume a 3 second reverberator.  The
... gain of this unit is left at its original value of approximately 0.75.

Append
... Now we add this unit to the initially empty tree.

Impulse *.6
... This will display an impulse response for the unit just added for the duration
... of 3.0*0.6 seconds.  In so doing, the list of commands will be made invisible.
... Always use either this form of the impulse command, or else specify an
... absolute duration.

d*.8
g*.95
... Using this pair of commands is the most popular way to construct the next
... unit reverberator.  The first command multiplies the delay of the scratch
... unit (which still remembers the first unit we built) by 0.8.  It leaves the
... gain unchanged.  The second command multiplies the gain by 0.95, leaving
... the delay unchanged (naturally).  Notice that the shortened form of the
... commands is acceptable, and that upper-case/lower-case distinctions are
... ignored.

a
... Now the new unit is appended to the unit already in the tree, giving a two
... unit mono reverberator -- but not a very good one yet.

i*
... An impulse response gives confirmation of that fact.  While there has been
... some improvement, the response is still too rough.

d*
g*
... So we create still another unit by modifying the last one in the same
... systematic way, using the default multipliers we set up the first time,
... 0.8 for delay and 0.95 for gain.

←
p
i.25
... Just for fun, we insert the new unit at the first of the tree (which still
... looks like only a list right now), so that we can look at its impulse response
... all by itself.  We look at only the first few spikes to emerge by using
... an absolute duration specification.

k y
... This deletes the unit we just added from the tree.  If the "y" had not been
... included, the program would have asked "REALLY KILL? ", and refused to kill
... the unit that the arrow pointed at if a "yes" (or shortened "y") was not
... typed in response.  This gives some protection from accidental death.

→
a
i*
... Now we move the arrow back to the bottom of the tree and stick the unit in
... in its natural order.  Once more we look at an impulse response, and see a
... still further improvement.

d*
g*
a
... Continuing in like fashion, we generate still another unit, which is then
... tacked on the bottom the same as all the rest.

d*
g*
... Plunging right ahead, we suddenly come up against a dire warning!  If it was
... really desirable, this unit could be added in with all the rest.  Experience
... has shown, however, that it rarely is a good idea.  Observe what happens next.

a
i*
... The response begins to show problems.  Not as dramatic as some, so maybe in
... this case it would be marginally acceptable; but in general you take your
... life in your hands if you use gains that small.  Let us see what we get
... without this last unit and then decide.

←
i*
... Because the response only includes units from where the arrow is back up to
... the input signal, we can see the effects of removing the last unit without
... actually killing it.  It appears that we would be better off not using that
... final unit, though it is a matter of judgment.

→
k y
... So we knock off the last unit, leaving us with a crude but effective mono
... reverberator.  Doubtless, it could stand some improvement; it serves to
... point out that much work remains to be done in better reverberator design.
... We could use it as is, or to double our pleasure, double our fun, use two
... output channels instead of just one!

help
?#Samples
"
#+2
... Refreshing our memory of the available commands, we ask for a more detailed
... description of the #Samples_delay command.  As you would expect, it exactly
... fits our needs.  So we get a copy of the last good unit (which we happen to
... be pointing at in the tree) into the scratch unit, and then modify it
... slightly.  Since this command was intended for just such use, it keeps the
... decay time the same for the new unit, insuring that the new channel has
... overall audio characteristics similar to those of the old channel.

b
... Now we make a bona fide stereo reverberator by adding the newly created unit
... as a branch, in parallel with the last unit already in the tree.  For the
... first time, we see the use of indentation in the display of the tree.  Up
... until this point no indentation was necessary, but with the addition of stereo
... we need to see which units connect with which output.  Arrow moving becomes
... slightly more complicated also.

←
→
↔
l
i*
... That sequence of commands should move the arrow right back where it was before
... we started moving it.  Then we remind ourselves of what the response of the
... first channel was, and look at the response of this channel for comparison.
... Although both channels seem very much alike, they are in fact slightly
... different from each other.  Thus we get more-or-less uncorrelated reverberation
... from two channels with only a little bit more computation and memory.

s u:demo
... So that we can come back some other day and touch this thing up (perhaps
... extending it to quad), we save the state of the world on file "U:DEMO.REV",
... on whatever area you are logged in on (or aliased to).  (Presumably you
... have previously made "U" a valid logical device name by use of the monitor
... assign command "A UDP2 U".)  When that other day arrives, the command
... "@u:demo" will return you to exactly the state you are in now, minus impulse
... display.

o [ins,
... Assuming you actually want the music compiler to do reverberation for you,
... this command will write out a file named "DSK:ALLPAS.MUS[INS,foo]" containing
... an instrument suitable for the music compiler to use.  The project name "foo"
... used in the above file name will, of course, be whatever programmer name you
... logged in with (rather than one you might be aliased to).

e
... Finally we're all done.  The Exit command is the most pleasant way to quit,
... since it cleans all the display stuff off the screen and restores your old
... page printer, just as if none of this had ever happened.  (And maybe it never
... has?!...)